Skip to content

docs: rewrite Lakebase Search as an architecture-first hub page - #6782

Draft
bgrenon wants to merge 21 commits into
mainfrom
docs/lakebase-search-hub
Draft

bgrenon wants to merge 21 commits into
mainfrom
docs/lakebase-search-hub

Conversation

@bgrenon

@bgrenon bgrenon commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

What

Rewrites /docs/ai/lakebase-search into the authoritative Lakebase Search hub page, and tidies the surrounding section.

  • Leads with the agent-native use case instead of a list of search types.
  • Explains the architecture with a diagram (storage/compute separation, lakebase_vector/lakebase_ann, lakebase_text/lakebase_bm25, hybrid as plain SQL).
  • Adds a short, real vector-search SQL example near the top.
  • Covers what you get: cost at scale, 100M+ vectors, scale-to-zero, hybrid search, and data searchable with no separate system to sync.
  • Reframes the vector/keyword/hybrid content as a short "which search to use" decision aid.
  • Keeps pgvector first-class and frames lakebase_vector as a compatible superset.
  • Groups the Lakebase Search pages (Overview, Get started, extension references) under one section in the sidebar.
  • Retires the outdated /guides/vector-search tutorial and redirects it to Get started.

Open questions (non-blocking)

  • Compression-ratio wording: sources differ, so it is left qualitative (no number printed).
  • Benchmark figures: the page links out and prints no raw numbers.

Related

A separate follow-up will modernize the embeddings guide to use Neon Functions, the AI Gateway, and Lakebase Search.

Preview

Leads with the agent-native use case and adds an architecture diagram.

Adds a what-you-get section and demotes search types to a reference section.

Keeps pgvector first-class and frames lakebase_vector as a compatible superset.

Pending before un-drafting: compression-ratio wording and benchmark publication clearance.
@vercel

vercel Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
neon-next Ready Ready Preview Nov 19, 2026 2:59pm UTC

Request Review

Rewrites the pgvector-limits and how-it-works sections as prose instead of stacked bullets.

Cuts editorializing and marketing phrasing for a direct, developer-first tone.

Folds the vector, keyword, and hybrid reference into the page flow instead of an appendix.
Removes the what-you-get section, folding its cold-start detail into how-it-works.

Simplifies the lede and drops benefit-speak so each fact appears once.
Replace the Mermaid architecture diagram with a self-contained themed SVG
embedded via InlineSvg so it follows the site's class-based dark mode, and
drop the redundant keyword-vs-vector explainer image.
Move the architecture section ahead of the pgvector problem section, drop the
Databricks callout box (attribution stays as the inline benchmark link), cut
rhetorical lines, and use subheadings and a query-type list for scannability.
Replace the memory-wall metaphor with a literal storage-vs-RAM statement, turn
the sync slogan into a plain sentence, and break the pgvector-limits paragraph
into a lead sentence and a scannable list.
Show vector plus keyword search fused with RRF in one statement, right after the
architecture diagram, and point to the get-started guide for the runnable version.
Swap the long hybrid RRF query for a minimal vector-search snippet after the
diagram, and link to the get-started guide for the full hybrid query.
Add a lead comment to the vector-search snippet, and replace the benchmarks stub
with the cleared comparative result (fastest and most cost-efficient, ~4x over
cloud pgvector) attributed to the Databricks blog, with no raw figures.
Give IVF and RaBitQ a what-and-why gloss, drop the pointer-chasing metaphor, make
the GIN comparison accurate (GIN scores all matching rows), gloss RRF, Jev, and
recall on first use.
Swap the IVF, RaBitQ, Block-Max WAND, RRF, and recall glosses for plainer wording,
and reframe the search-types section into a short decision aid without the
duplicated extension links.
Give the Lakebase Search product entry an Extension reference section with the
three extension pages, move those pages out of the alphabetical Postgres
extensions list, drop the duplicate nested entry, and remove the Platform
cross-link so the Overview breadcrumb resolves cleanly.
Use present tense and link the Databricks benchmark for the full results.
Remove the stale pgvector plus HNSW tutorial, 308-redirect /guides/vector-search
to the Lakebase Search get-started page, and repoint its inbound links.
The surrounding text is about pgvector, so link the pgvector extension page.
Report the Databricks VectorDBBench figures with needs-verification markers on
the unreproduced numbers, keep the cleared 4x cost claim, and lead the page with
the agent-native value instead of the three search types.
Replace the architecture diagram with a themed SVG showing stateless compute,
separated storage, and both engines, and add a contrast diagram for the
index-in-RAM-versus-storage point. Both SVGs theme via the site dark class.
Rewrite the surrounding prose to carry scale-to-zero, cold-start, and the
storage-not-RAM payoff instead of restating the pictures.
Draw the search index as a single labeled block instead of a bar stack that
was misread as table rows. Metadata-stripped and dark-mode themed as before.
Tighten the cold-start, vector-search, keyword/hybrid, pgvector, and separate-
vector-database wording, trim the acronym hand-holding, and simplify the
benchmark list lead-in.
Keep the cleared 4x cost comparison and the Databricks benchmark link, and drop
the unverified throughput, recall, latency, and single-CU numbers.
Resolve conflicts: keep the PR's Lakebase Search link in
content/docs/extensions/pgvector.md (accept current updatedOn) and keep
content/guides/vector-search.md retired per this branch.

@philip philip left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed by Philip with his agent (live-tested):

Accurate, good to merge. Tested on a fresh production project:

  • lakebase_vector installs vector 0.8.7, and <=>, <->, and <#> work.
  • A lakebase_ann index serves the <=> query, and a row inserted after the index build comes back first.
  • lakebase_ann_prewarm and lakebase_tokenizer exist.
  • The Databricks post backs "4x" and the VectorDBBench 100M benchmark.
  • /guides/vector-search redirects to Get started on the preview, and nothing still links to it.

Optional:

  • Seven files only get prettier reformatting (grafana-cloud, opentelemetry, schema-diff, vercel-connection-methods, import-data-assistant, regions, repeat). Dropping them keeps the diff focused, and the regions.md reflow could collide with NAT IP updates.
  • In opentelemetry.md, step 3 already renders on the image line. A blank line before it fixes that.
  • All four hub cards use icon="openai".
  • The lakebase_* pages leave the Extensions sidebar list. Intended?

This branch was successfully deployed

1 active deployment
Preview – neon-next — 30be5859 Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants